sucrase

What is sucrase?

Sucrase is a super-fast alternative to Babel for compiling modern JavaScript into older versions that are more widely supported. It focuses on compiling non-standard syntax like JSX, TypeScript, and Flow into standard JavaScript, offering significant speed improvements over Babel.

What are sucrase's main functionalities?

JSX Compilation

Sucrase can compile JSX syntax used in React applications into standard JavaScript, making it easier to run in environments that do not support JSX natively.

import React from 'react';
const App = () => <div>Hello, Sucrase!</div>;

TypeScript Compilation

Sucrase can compile TypeScript code into plain JavaScript, allowing developers to use TypeScript's type checking features without worrying about compatibility.

import express from 'express';
const app: express.Application = express();

Flow Compilation

Sucrase provides support for Flow, a static type checker for JavaScript. It can strip Flow type annotations and compile the code into standard JavaScript.

/* @flow */
function square(n: number): number {
  return n * n;
}

Other packages similar to sucrase

babel

Babel is a widely used compiler for writing next generation JavaScript. It's more flexible and configurable than Sucrase, but generally slower due to its comprehensive feature set.

typescript

The TypeScript compiler not only compiles TypeScript into JavaScript but also provides type checking. It's similar to Sucrase's TypeScript compilation feature but includes type checking, which Sucrase does not.

esbuild

esbuild is an extremely fast JavaScript bundler and minifier. It offers similar compilation features to Sucrase but also includes bundling and minification, making it a more comprehensive tool for building web applications.

README

Sucrase

Try it out

Sucrase is an alternative to Babel that allows super-fast development builds. Instead of compiling a large range of JS features down to ES5, Sucrase assumes that you're targeting a modern JS runtime (e.g. Node.js 8 or latest Chrome) and focuses on compiling non-standard language extensions: JSX, TypeScript, and Flow. Because of this smaller scope, Sucrase can get away with an architecture that is much more performant but less extensible and maintainable.

Current state: The project is in active development. It is about 20x faster than Babel and about 8x faster than TypeScript, and it has been tested on hundreds of thousands of lines of code. Still, you may find correctness issues when running on a large codebase. Feel free to file issues!

Sucrase can build the following codebases with all tests passing:

• Sucrase itself (6K lines of code excluding Babylon fork, typescript, imports).
• The Benchling frontend codebase (500K lines of code, JSX, imports).
• Babel (63K lines of code, flow, imports).
• React (86K lines of code, JSX, flow, imports).
• TSLint (20K lines of code, typescript, imports).
• Apollo client (34K lines of code, typescript, imports)
• decaffeinate and its sub-projects decaffeinate-parser and coffee-lex (38K lines of code, typescript, imports).

Transforms

The main configuration option in Sucrase is an array of transform names. There are four main transforms that you may want to enable:

• jsx: Transforms JSX syntax to React.createElement, e.g. <div a={b} /> becomes React.createElement('div', {a: b}). Behaves like Babel 7's babel-preset-react, including adding createReactClass display names and JSX context information.
• typescript: Compiles TypeScript code to JavaScript, removing type annotations and handling features like enums. Does not check types.
• flow: Removes Flow types, e.g. const f = (x: number): string => "hi"; to const f = (x) => "hi";. Does not check types.
• imports: Transforms ES Modules (import/export) to CommonJS (require/module.exports) using the same approach as Babel. With the typescript transform enabled, the import conversion uses the behavior of the TypeScript compiler (which is slightly more lenient). Also includes dynamic import.

The following proposed JS features are built-in and always transformed:

• Class fields: class C { x = 1; }. This includes static fields but not the #x private field syntax.
• Export namespace syntax: export * as a from 'a';
• Numeric separators: const n = 1_234;
• Optional catch binding: try { doThing(); } catch { }.

There are some additional opt-in transforms that are useful in legacy situations:

• add-module-exports: Mimic the Babel 5 approach to CommonJS interop, so that you can run require('./MyModule') instead of require('./MyModule').default. Analogous to babel-plugin-add-module-exports.

Usage

Installation:

yarn add --dev sucrase  # Or npm install --save-dev sucrase

Run on a directory:

sucrase ./srcDir -d ./outDir --transforms typescript,imports

Register a require hook with some reasonable defaults:

// Register just one extension.
import "sucrase/register/ts";
// Or register all at once.
import "sucrase/register";

Call from JS directly:

import {transform} from "sucrase";
const compiledCode = transform(code, {transforms: ["typescript", "imports"]});

There are also integrations for Webpack, Gulp, and Jest.

Motivation

As JavaScript implementations mature, it becomes more and more reasonable to disable Babel transforms, especially in development when you know that you're targeting a modern runtime. You might hope that you could simplify and speed up the build step by eventually disabling Babel entirely, but this isn't possible if you're using a non-standard language extension like JSX, TypeScript, or Flow. Unfortunately, disabling most transforms in Babel doesn't speed it up as much as you might expect. To understand, let's take a look at how Babel works:

1. Tokenize the input source code into a token stream.
2. Parse the token stream into an AST.
3. Walk the AST to compute the scope information for each variable.
4. Apply all transform plugins in a single traversal, resulting in a new AST.
5. Print the resulting AST.

Only step 4 gets faster when disabling plugins, so there's always a fixed cost to running Babel regardless of how many transforms are enabled.

Sucrase bypasses most of these steps, and works like this:

1. Tokenize the input source code into a token stream using a trimmed-down fork of the Babel parser. This fork does not produce a full AST, but still produces meaningful token metadata specifically designed for the later transforms.
2. Scan through the tokens, computing preliminary information like all imported/exported names.
3. Run the transform by doing a pass through the tokens and performing a number of careful find-and-replace operations, like replacing <Foo with React.createElement(Foo.

Because Sucrase works on a lower level and uses a custom parser for its use case, it is much faster than Babel.

Performance

Currently, Sucrase runs about 20x faster than Babel (even when Babel only runs the relevant transforms) and 8x faster than TypeScript. Here's the output of one run of npm run benchmark:

Simulating transpilation of 100,000 lines of code:
Sucrase: 469.672ms
TypeScript: 3782.414ms
Babel: 9591.515ms

Project vision and future work

Performance improvements

• Rewrite the code to run in WebAssembly, either by changing it to be valid AssemblyScript or by rewriting it in Rust.
• Explore the idea of a JIT to optimize the various token patterns that need to be matched as part of code transformation.

New features

• Implement more integrations, like a Rollup plugin.
• Emit proper source maps. (The line numbers already match up, but this would help with debuggers and other tools.)
• Rethink configuration and try to simplify it as much as possible, and allow loading Babel/TypeScript configurations.
• Explore the idea of a tool that patches a Babel/TypeScript installation to use Sucrase instead, to make it even easier to try Sucrase on an existing codebase.
• Explore the idea of extending this approach to other tools, e.g. module bundlers.

Correctness and stability

• Add more open source projects to the suite of projects that are tested automatically.
• Set up a test suite that runs the compiled code and ensures that it is correct.
• Add integrity checks to compare intermediate Sucrase results (like tokens and the role of each identifier and pair of curly braces) with the equivalent information from Babel.
• Fix some known correctness loose ends, like import hoisting and fully replicating the small differences between Babel and the TypeScript compiler.

License and attribution

Sucrase is MIT-licensed. A large part of Sucrase is based on a fork of Babylon, which is also MIT-licensed.

Why the name?

Sucrase is an enzyme that processes sugar. Get it?